Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/BARNET/FREENET/DEVOS/FREEDIAL.ARC/!FreeDial/!Help

Text File | 1996-04-14 | 29KB | 674 lines

!Help file for FreeDial 0.23, 14 Apr 1996 Gert-Jan de Vos

Contents
========

    1 FreeDial

    2 Provider setup
      2.1 Provider
      2.2 Location/Phone
      2.3 Login
      2.5 Configure Resolver

    3 The Modem setup
      3.1 Modem
      3.2 Serial port driver
      3.3 Serial port speed
      3.4 Dial attempts
      3.5 Redial delay

    4 TCP/IP setup
      4.1 TCP/IP Stack
      4.2 Script
      4.3 Brief login

    5 Dialling
      5.1 Trouble shooting

    6 Script file syntax

    7 Modem drivers

    8 TCP/IP Stack support

    9 Further Configuration

    10 Hints and Tips

    11 Bugs

    12 Acknowledgements

    13 Copying



1 FreeDial
==========

FreeDial dials your Internet provider, logs in and sets up the Internet
software on the RISC OS side. All important setups are grouped in one simple
dialogue box, and you can simply select or edit one of the available choices
from pop-up menus. I wrote FreeDial specifically to to log in to my provider
which uses dynamic IP address binding. Probably SlipDial can handle this too,
but I found SlipDial much too difficult for my liking and wrote this.

FreeDial must have a directory where it can keep its configuration, this is
the Files.FreeDial directory in either !FreeUser or !Internet. The supplied
FNInstall or AInstall will install the FreeDial configuration in your
internet package. Read the 'Further configuration' paragraph at the end if
you don't use FreeNet or Acorn Internet. I will now describe all entry
fields of the FreeDial configuration dialogue in such a way that someone new
to Internet can set up his or her own connection. Someone familiar with the
Net, just start FreeDial and select your setup, use the !Help application to
get more information. Have a look at the end of this file for more technical
details about the syntax of the script files, the modem drivers and more
complex configuration.

If you have not yet installed Acorn Internet or FreeNet and you want to know
how to do it, there is information about internet software installation in
the Install file in the FreeDial archive.

The basic idea behind FreeDial is that it defines a set of system variables
which hold the parameters for a particular Internet connection. The TCP/IP
stack startup scripts then use these variables to configure the stack. These
variables are:

Inet$Phone         - The selected phone number of your provider
Inet$ModemDriver   - The serial port driver from !SerialDev
Inet$ModemPort     - The serial port number
Inet$ModemSpeed    - The baudrate of the serial port connection

Inet$NodeName      - The login name and name of your machine
Inet$Password      - The password for your account
Inet$Domain        - The internet domain name in which your machine will be
                     connected
Inet$FullName      - The full internet name of your machine, ie concatenation
                     of Inet$NodeName and Inet$Password. This is not defined
                     by FreeDial, but when defined in the script, it will
                     overrule the NodeName and Domain variables for resolver
                     configuration by 'ResConf'.

Inet$LocalIP       - The numeric internet address of your machine
Inet$RemoteIP      - The numeric internet address of the machine you connect
                     to
Inet$RouterIP      - The numeric internet address of the machine which routes
                     your data. optional, defaults to <Inet$RemoteIP>

Inet$NameServer1IP - The numeric internet address of the first nameserver
                     machine
Inet$NameServer2IP - .. 2nd ..
Inet$NameServer3IP - .. 3rd ..


2 Provider setup
================

2.1 Provider
------------
Start the configuration by selecting or adding your Internet Service
Provider from the pop-up menu. A provider entry holds configurations for
nameservers, phone-numbers, login scripts and login accounts. When editting a
provider entry you need to specify a name for the provider (which must also
be a valid filename), the internet domain in which the provider lives, and
up to three numeric internet addresses for the nameserver machines of this
provider. When you can use the machine you dial into as a nameserver, select
'NS1=RemoteIP'. If your provider has only one or two nameservers, leave the
last field(s) empty.

If your provider shows the domain or nameserver information in the login
procedure, you can leave these fields blank and define the variables
Inet$Domain, Inet$FullName or Inet$NameServer#IP in the scriptfile with the
commands GetWord and GetIP.

2.2 Location/Phone
------------------
Now select or add the location and phone number of this provider you want to
dial. The phonenumber depends on the chosen location.

2.3 Login
---------
You must enter the following data for your provider account:
Login: the name under which the provider's computer knows you
The login name will also be used as the name of your machine unless you
redefine Inet$NodeName or Inet$FullName in the script file.
Password: The password for this login name. When you select 'Interactive
password', FreeDial will ask you to type it in as soon as you click
'Dial', but wil NOT save it to disc. Passwords are stored encoded, but if you
really want you can decode them (especially since the source is available).
Furthermore, anyone can use your account when the password is stored.

There are two more fields where you can enter the numeric internet addresses
of your machine and the machine to which you connect on this login account.
Many providers don't supply constant addresses for these but rather give you
temporary addresses which are shown when you select SLIP in the login
procedure. In this case you can leave the address fields open, and use the
GetIP command in the script file to define the variables:
  Inet$LocalIP
  Inet$RemoteIP
  Inet$RouterIP
The RouterIP address defines the machine which is routing your data, this is
very probably equal to Inet$RemoteIP. In this case you can leave
Inet$RouterIP undefined.

2.4 Configure Resolver
----------------------
When you have selected a provider and login with static defined IP addresses
for LocalIP, RemoteIP and NameServerIP, you can press this button to update
the resolver module configuration using these addresses. This does actually
the same as the 'ResConf' command from the script file, but can obviously
not use settings defined in the script ie. dynamic IP addresses.


3 Modem setup
=============

3.1 Modem
---------
Select a suitable modemdriver for your modem. Usually HayesTone will be the
one you need. The modemdriver defines the commands needed to communicate with
the modem. The drivers can not be editted from FreeDial as this should not
often be needed. At the end of this file is a description of the modemdriver
file, have a look at it in case you need to create or change a modemdriver.

3.2 Serial port driver
----------------------
Select one of the serial port drivers from the ones your copy of !SerialDev
supports. When your serial controller supports more than two ports (none of
the internal ones do), you can select a port number other than port 0.
Remember that you need the bugpatched versions of the Internal and
InternalPC drivers as supplied with FreeNet. Check the info window from the
SerialDev selection menu, you need at least version 1.13 for the internal
drivers.

3.3 Serial port speed
---------------------
Select a serial transfer speed which matches your setup, sensible maximum
values are:

pre-A5000 machines:          19200
pre-RiscPC machines:         19200 (38400 or 57600 is reported to
                                    work reliably on somemachines)
RiscPC:                      anything up to 115200 will do fine.
High speed serial upgrade:   as high as your card allows (the modem may
                                             give up at 57600 or 115200)

Remember that data compression may result in data rates between your computer
and modem up to 4 times that over the phone line. This is also often the
maximum speed the modem will accept.

3.4 Dial attempts
-----------------
When the modem reports a busy phone line, it will retry up to the number of
times you specify. You can deselect Attempts to keep trying to contact a
busy line. Other problems during the dial procedure will just hangup the
phone and leave the dial window open, so you can inspect what is going on.

3.5 Redial delay
----------------
Select the redial delay from the Every menu. This is the delay after which
FreeDial will redial after a previous BUSY line.

4 TCP/IP setup
==============

4.1 TCP/IP stack
----------------
This version of FreeDial supports the FreeNet and Acorn Internet package.
When FreeDial starts, it detects which of these is available but will get
confused if both are booted. Select the stack you want to use. A provider
setup will work with either stack, you can switch later on if you wish.

4.2 Script
----------
Select or edit the login script for the selected provider. You can have
different scripts, for instance to use different drivers (SLIP/PPP). The
script contains some simple commands to communicate with your provider's
login dialogue to get the Internet connection established. Look at paragraph
6 in this file for a description of all available script commands. Have a
look at one of the supplied scripts, the commands should be easy to
understand. You can include RISC OS *commands to start other software. When
you enter a new script name in the script menu, FreeDial will open a copy of
the 'DefScript' file in !FreeDial in your default text editor. This default
script is a basic SLIP script which you can edit for your provider. When you
save it, you can use it with your selected provider.

FreeDial will create the system variable 'Inet$Password' which holds the
selected password while the script is running. This makes it easy to steal
someones password, but it is needed in PPPdriver scripts which use the
PPPdriver to log in.

The TCP/IP stack selection defines the InetStack$Path variable. This means
that you can call support scripts for the selected stack through this path.
Your script should include the line:
  Task InetStack:SLIP
to start the SLIP driver for the configured stack.

Usefull example scripts are:
it.VOL PPP_PAP     Very simple script to start PPP protocol with Password
                   Authentication Protocol.
nl.TUE-DialIn SLIP My script for a fairly standard SLIP login with dynamic
                   IP addresses
nl.HCC SLIP        A script which needs the SendGS command for an unusual
                   login prompt reply
za.OnWe            A script for a menu-based login system with many dynamic
                   settings.


5 Dialling
==========

When you have reached this point, you have completed the configuration of
FreeDial and FreeNet! Now first press the Save button:

Quit - Ends FreeDial, does not update the configuration
Save - Saves the displayed configuration as the default. FreeDial will use
       this next time.
Dial - Use the displayed settings to Dial the provider and start FreeNet.

Now it's time to try Dial. If all goes well, you should see the login
procedure roll by in the dial window, the disc rattles a little and FreeDial
quits without anything else happening. This means that the internet software
has started and your machine is on the internet. You now need other software
to do something with it. You can try 'ping <Inet$RemoteIP>' and for instance
'ping www.acorn.co.uk' from the command line to verify your connection. When
it works, ping reports connection statistics for each connection attempt.
Press <Esc> after a couple of seconds to quit ping.

5.1 Trouble shooting
--------------------
If it doesn't work:
- Check all settings in the Setup window again. Is your modem on and
  connected?
- Does the script work? Remove the 'Quit' command to keep the dial window
  open and inspect the logfile by saving it from 'Save log'. Note that
  anything you sent is enclosed in '<>'s. <PASS> is the sent password and
  <CR> is a Carriage Return character. Check which command fails and compare
  the script with a manual login procedure from a terminal program.
- Type 'Show Inet$*' from the command line to inspect which settings FreeDial
  uses to start the Internet software.
- If Address Exception errors start when FreeDial has just finished the login
  procedure, you are probably using an old version of the Internal serial
  device drivers. Check the Info window from the Serial driver menu in the
  Modem setup window. You should use version 1.13 (bugfixed) or later of the
  Internal and InternalPC drivers. These are supplied with FreeNet.
- If 'ping <Inet$RemoteIP>' works but named addresses don't, maybe the
  nameresolver doesn't work. Have you entered correct nameserver IP addresses
  in the Provider setup? Does your script have a 'ResConf' command before the
  internet software starts, to configure the resolver module? Check the
  resconf and resboot files 'ResConf' creates. Does resconf have lines for
  three nameservers? Otherwise 'ResConf' won't create them.
- The 'Brief login' option was suggested by someone who tries to run a
  non-FIFO port higher than 19k2. Since FreeDial does less screen updates
  during a brief login, this might reduce data errors during the essential
  login data transfer. You can try this, but I don't recommend speeds above
  19k2 on non-FIFO ports.
- If everything works but very slow, the serial port speed is too high. Have
  you used SerialDeviceDriver 0.22 and a SerialBuffer utility? Try the same
  setup but with a 9600 baud serial port connection.


6 Script file syntax
====================

The script file contains one command per line. Empty lines and lines starting
with the remark characters '#' or '|' are ignored. The available commands are:

Answer
------
Switch modem to auto answer mode, and wait for a connection message. Use this
after the initial login in a script for a DialBack login.

Send <args>
-----------
Sends all its arguments up to but not including the next linefeed to the modem

SendCR <args>
-------------
Sends all its arguments up to and including the next linefeed to the modem

SendGS <args>
-------------
GS Transforms all its arguments up to but not including the next linefeed and
sends the resulting string to the modem. This can be used to send system
variables and control codes, like:
  SendGS slip:<Inet$NodeName>|I<Inet$Password>|J

Wait <args>
-----------
Read input from modem until a string matches (case sensitive) the
given argument exactly up to but not including the next linefeed

GetWord <varname>
-----------------
Read from the modem the next sequence of non-whitespce characters and place
this in the given variable.
Use these for setting:
  Inet$NodeName
  Inet$Domain
  Inet$FullName
When Inet$FullName is defined, it will overrule the definitions of the other
two. Inet$NodeName becomes the part of Inet$FullName up to the first dot, the
rest is copied to Inet$Domain. If Inet$FullName is left undefined,
Inet$NodeName will default to the login name and Inet$Domain to the domain
configured in the provider edit dialogue.

GetIP <varname>
---------------
Read input from modem until a string exactly matches a valid numeric IP
address. Place the IP address string in the system variable given in the
argument.
Use this for setting:
  Inet$LocalIP
  Inet$RemoteIP
  Inet$RouterIP
  Inet$NameServer1IP
  Inet$NameServer2IP
  Inet$NameServer3IP
In scripts which connect to Providers who display these addresses in the
login procedure.

ResConf
-------
This command configures the DNS name resolver by editing the file
InetDBase:resconf and replacing the fileInetDBase:resboot with values for
your current configuration. It uses the Inet$* variables so you can configure
the resolver for a dynamic configuration from the login script. The ResConf
command should be given after the definition of the Inet$* variables in the
script and before starting the driver. When the INetDB module is already
loaded, it will be reinitialised to make the new configuration effective.
ResConf recognises either the 'domain' or 'search' keyword in the resconf
file for configuring the domain name. As the 'search' keyword can take
several domain parameters, only the first one is replaced. You can still edit
the other search paths manually.

The 'Configure Resolver' button in the Provider setup window does the same,
but only when you click on it and it can obviously not use settings defined
during the login script execution. This means you have to click it after
selecting a new provider unless the script includes a 'ResConf' command.

TimeOut <n>
-----------
Change the timeout period to 'n' centi-seconds. The default timeout period is:
  5 sec while initialising the modem
  1 min while dialling and upto the first TimeOut command in the script.

Login
-----
Send the selected login string to the modem, followed by a return character.

PassWord
--------
Send the selected password to the modem, followed by a return character.

Pause <n>
---------
Do nothing for 'n' seconds.

*Command
--------
Any line preceded by a * is directly passed to the Operating System
Commandline Interpreter. Use this for eg. *Set, *Pin, *Filer_OpenDir ...

Task
----
Like * but now the given command runs in its own memory environment,
preventing FreeDial from being overwritten and crashing. Use this to run
commands which are actually programs, ie the driver startup script.

Echo <args>
-----------
Display the argument in the dial window status field when the script
processing reaches this command. Useful for diagnostic messages like 'SLIP
driver is starting'

Remark
------
Any empty line or line preceded by a '#' or a '|' is ignored

Quit
----
When the script has executed successfully and reaches this command, FreeDial
will quit. When quit is not found before the script ends or a problem occurs
before the end of the script, the program will keep its windows open and
you can analyse the login dialogue.


7 Modem drivers
===============
The modem drivers cannot be edited from FreeDial's frontend, I don't think
they need to be changed very often. You can have as many modem driver files
as you need, and just pick the one you need from the frontend. The modem
driver files can be found in <FreeUser$Dir>.Files.FreeDial.Modems. Each file
has the following entries which are MessageTrans_GSLookup-ed before they are
send to the modem:

Init:
Dial:
Answer:
OK:
CONNECT:
BUSY:
NO CARRIER:

This means that you can include any control characters by using the GSTrans
representation (eg: '|M'), and you must escape any special characters. The
'|W' sequence causes a 1 sec. delay in the command. The Dial string has one
parameter '%0' which is replaced with the selected phonenumber when a number
is dialled. All entries default to a standard Hayes modem string, so the
Hayes driver could actually be empty. Basically copy a driver similar to one
you need, and edit it.

FreeDial tries to read the message after the CONNECT message from the modem
and interpretes this as the line speed, displayed in the Line field of the
Dial window. Most modems can display different messages after the CONNECT
message but \V2 in the init string enables the line speed indication. If the
modem does not give the line speed or gives another CONNECT argument, the Line
display will either show '???' or the argument found instead. As long as your
modem gives a newline between the CONNECT message and the incoming data, the
line speed detection attempts will not influence the script processing.

8 TCP/IP Stack support
======================
FreeDial now uses the Obey scripts in the directory
<FreeDial$Config>.Stacks.<StackName> to support several Internet packages. A
directory for an Internet package contains:

  !Available - Sets the variable Inet$StackBooted to the name of the stack
               if the filer has seen this software.
  !Ensure    - Sets the variable Inet$StackLoaded to the name of the stack
               if this stack is already loaded.
  !OnLine    - Common commands to execute when a connection using this stack
               has started. Can be used for Call logging, locating the !Shutdown
               script etc.
  !ShutDown  - ShutDown this stack.
  !StartUp   - Load this stack without a driver and sets the variable
               Inet$StackLoaded to the name of the stack.

And a number of Obey scripts for loading available drivers for this stack,
like:

  CSLIP      - SLIP with header compression
  PPP        - Point to Point Protocol
  PPP_PAP    - PPP with Password Authentication Proticol
  SLIP       - Serial Line Internet Protocol.

The !* files are used by FreeDial and must be available. The driver scripts
are for use in the login script, like 'Task InetStack:SLIP'. Please send me
startup scripts for any other internet stacks configurations you have made
so I can include these in a new distribution.

9 Further Configuration
=======================

FreeDial stores it configuration in the directory <FreeDial$Config> which is
defined in the !Run file to point to either !FreeUser.Files.FreeDial or
!Internet.Files.FreeDial. FreeDial stores its configuration files outside its
own directory so that FreeDial can be upgraded without changing your
settings.

When you replace the last line in !FreeDial.!Run with:

Run <FreeDial$Dir>.!RunImage -dial

FreeDial will immediately start dialling when it runs, and you can not change
the settings, unless <Alt> is held when FreeDial starts.

Furthermore, any of the default settings saved by the 'Save' button, can be
overruled by the following command line switches:

  -stack <stack name>
  -provider <country>.<provider name>
  -location <location>
  -script <scriptfile>
  -login <login name>
  -modem <modem driver>
  -driver <serial port driver>
  -port <serial port number>
  -baud <serial baud rate>
  -attempts <max dial attempts> ; 0 means unrestricted
  -resconf                      ; re-configure the resolver for the given setup
  -brief                        ; Show only status during login
  -verbose                      ; Show login procedure log
  -dial                         ; Start dialling immediately after startup

The given argument for each setting must match a valid option, matching is
case insensitive.

FreeDial should handle all the necessary configuration of FreeNet or Acorn
Internet needed to start a SLIP or PPP connection with the standard
distribution. Let me know if you have a configuration which can not be
handled by FreeDial.

FreeDial handles just a basic serial line connection with the file
InetStack:<DriverName>, like:
   InetStack:SLIP or
   InetStack:PPP
You can add extra configuration to these files by editing these.

The script command 'ResConf' edits the file InetDBase:resconf and
replaces the 'domain', 'search' and 'nameserver' lines with entries for the
current connection. You can still edit or add other lines in this file,
FreeDial will leave these unchanged.

The 'ResConf' command also generates the file InetDBase:resboot. Let me
know if you need to keep customized settings in the resboot file, and so
don't like it to be overwritten.

The 'ResConf' command is written for the InetDB module supplied with FreeNet
and does nothing when InetDBase$Path is not defined.

Note that FreeDial's login script can include any commands. You can use this
start other Internet software, or like I do, to *Pin the !ShutDown icon in a
handy place. Remember to use 'Task' for anything which starts an actual
program, * will only handle simple internal commands:

  *Filer_Opendir ADFS::IDEDisc4:$.Internet.Apps
  Task Run ADFS::IDEDisc4:$.Internet.Apps.!ArcWeb
  *Pin InetStack:!ShutDown 0 244

You can of course reduce the disc space by removing the country and provider
directories in !FreeNet.Files or !Internet.Files for any providers you don't
use. Please do include all providers and countries if you copy FreeDial for
another user.

If you call FreeDial from an obey file, you can find out what happened by
inspecting the return code after FreeDial has completed. Sys$ReturnCode will
contain one of these values:
  0 Connected
  1 Never dialled
  2 Failed to connect

10 Hints and Tips
=================
- The supplied provider configuration files take up a lot of disc space when
  you unpack them. You may not notice this as it only holds small files. The
  large nuber of small files and deep directory structure cause FileCore to
  allocate a larger number of disc sectors for them though. The providers
  take up about 1MB now on my disc. This all means that you can save up some
  disc space by removing the country hierarchies or even providers you
  don't use in the <FreeDial$Config>.Providers directory. Please keep the
  complete set of providers in the archive for when you give FreeDial copies
  to other people. The Providers don't take up much space in the archive
  anyway.
- FreeDial will detect it when one of the supported TCP/IP stacks is already
  running when it starts. This means that you can run it on an Ethernet
  machine without changing the configuration. FreeDial will use the running
  stack and add the dial-up support for an Internet link.
- a PPP login will generaly not display the dynamically assigned Local and
  Remote IP numbers. This means that you can't use the GetIP command with
  the ResConf command to configure a PPP login. In fact the PPP driver
  handles the necessary IP number configuration itself while the resolver
  configuration can be ignored for such a login. The ResConf command is
  still usefull since the domain must still be updated in the resolver
  config files. This means: just include the ResConf comand and don't worry
  about IP-getting the IP numbers for the resolver files, PPP will take care
  of the important things for you.
- The !OnLine and !ShutDown scripts as supplied implement call logging and
  !ShutDown icon location. There is no support in the !FreeDial !RunImage
  itself for call logging or shutdown, you can easily change the current
  implementation if you like. Let me know if you can come up with anything
  better.
- The 'Pin !ShutDown' commands in !OnLine and !ShutDown can give problems
  with Pinboard status saving utilities like SaveDesk. You can replace them
  by 'AddTinyDir InetStack:!ShutDown' and 'RemoveTinyDir InetStack:!ShutDown'
  commands respectively.

11 Bugs
=======
These are the problems which still exist in FreeDial 0.23 and that I know of.
Let me know if you find any others.
  - Login names may not have ':' characters in them
  - Passwords may not have high-bit set characters in them
  - character code 23 '|W' is always interpreted as a 1 sec. delay and can't
    be send (it can now with the SendGS command).
  - Using a filingsystem which allows >10 char filenames for providers etc. may
    give unexpected results
  - The code for the country hierarchy has become rather chaotic and I'm
    surprised it seems work. I should really tidy this, but meanwhile
    version 0.23 seems stable.
  - Since FreeNet and Acorn Internet both define the same system variables, you
    can't have both installed and booted using FreeDial to select either one.
    It would be possible to change the !Boot scripts of these, but that would
    complicate FreeDial installation.


12 Acknowledgements
==================
I like to thank the following people who contributed in the development of
FreeDial:

Ian Jeffray for the source code of EasyDial
Ernst Berends for the basic idea, early testing and modem supply
Jaques Haubrich and Joost Carpay for early testing
Dawie van den Bergh, Richard Walker, Chris Curzon and especially Sergio
Monesi for their ideas and help for further improvement.
Thanks to Rob Ward for his Template improvement.

13 Copying
==========

FreeDial was written by Gert-Jan de Vos. I started by modifying EasyDial by
Ian Jeffray of Riscy Developments, the Dial window and parts of the
source-file dial.c remained from that. I have released FreeDial and its
source as FreeWare under the condition that it is distributed free and only
with all its original files. Send me any changes/additions/problems so that
I can release a newer version for everyone. I'm especially interested in
additional provider setup files. With a large set of provider configuration
files, new users just need to select theirs which makes running Internet
software very simple.

Don't forget to remove the 'Login' file from a Provider directory you wish to
copy for someone else. Your password is encoded, but FreeDial will be able to
use it, and thus anyone using your Login file with your provider!

In order to compile the FreeDial sources you need a C compiler and OSLib 5.1.

Gert-Jan de Vos
Benedenbeekloop 18
5662 HL Geldrop
the Netherlands
[phone]
[e-mail]